home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 098 / driver.dqc / driver.doc
Encoding:
Text File  |  1985-04-05  |  7.5 KB  |  239 lines
  1. Universal Drivers for Telink, Minitel, Fido, FidoNet,
  2. Sysop, and Rolodex.
  3.  
  4. T. Jennings 27 Nov 84
  5.  
  6.  
  7.     All IO drivers MUST conform to this standard. All software
  8. will do screen, clock, and modem IO through these drivers.
  9.  
  10. GENERAL
  11.  
  12.     The driver must be assembled using the LATTICE.ASH and
  13. MODEL.ASH include files. These define function declarations, and help
  14. make the code model indifferent. All functions must automatically
  15. confine themselves to the three different models using the .ASH files.
  16. These are:
  17.  
  18. SMALL
  19.     Single code segment and single data segment. All pointers are
  20. short, 16 bits. When access is needed to either of the segments (code
  21. group or data group) ALWAYS reference the equates and definitions in
  22. the .ASH file. Locally defined dgroup variable can be accessed after:
  23.  
  24.     mov    ax,data
  25.     mov    ds,ax
  26.  
  27.     This is done for you in the macros.
  28.  
  29. LARGE
  30.     Single code group, many data groups. Pointers are 32 bits. You
  31. can assume that all driver statics are really static, ie. in DGROUP
  32. space. Locally defined dgroup variable can be accessed after:
  33.  
  34.     mov    ax,data
  35.     mov    ds,ax
  36.  
  37.     This is done for you in the macros.
  38.  
  39. ROM
  40.     This is the same as SMALL, except there is a globally defined
  41. location in PGROUP, called DATASEG, that is where the current data
  42. group is located. This is for ROM type code; if you need to access
  43. local dgroup variables, as in an interrupt routine, use:
  44.  
  45.     mov    ds,cs:dataseg
  46.  
  47.  
  48.  
  49. TIPS:
  50.  
  51.     You should put certain functions into seperate files, along
  52. the following guidelines. The reason is that some programs use only
  53. the screen functions (Rolodex, etc) some use only the modem functions
  54. (ViaDev, etc) and some use both (Fido, Telink, etc). Seperating them
  55. will allow not loading the whole damn thing everytime.
  56.  
  57.     Also, lconout must be in a seperate file; sometimes it is
  58. necessary to use the standard MSDOS lconout() so that redirection can
  59. still be used. PLINK will complain about multiple defineds unless you
  60. seperate them.
  61.  
  62.     DRIVER.H defines the static variables that must be set. These
  63. are:
  64.  
  65.  
  66. CRT Variables
  67.  
  68. int lines;    Number of lines on the screen, i.e. 24 for a
  69.         24 line screen.
  70.  
  71. int cols;    The number of columns on the screen, i.e. 80
  72.         for an 80 column screen.
  73.  
  74. int top;    A mistake, but this is the top line NUMBER. Zero
  75.         is just about universal, though, if the hardware
  76.         starts its line numbering at 1, set it to 1.
  77.  
  78. int bottom;    The last line NUMBER, i.e. if the first line
  79.         number is 0, then for a 24 line screen this will
  80.         be 23.
  81.  
  82.  
  83. char ulcorner = '+';    These are the characters used in drawing
  84. char urcorner = '+';    boxes on the screen. if DRIVER.H is used,
  85. char llcorner = '+';    they have the indicated defaults.
  86. char lrcorner = '+';    They can be changed at init() time.
  87. char vertbar = '|';
  88. char horizbar = '-';
  89.  
  90. char graph_on[];    These are null terminated strings, used to
  91. char graph_of[];    enable and disable graphics mode. If they are 
  92.             not null, then they are sent out before any 
  93.             attempts are made to draw the graphic 
  94.             characters above. These must be set at init() 
  95.             time.
  96.  
  97.  
  98. MODEM PARAMETERS
  99.  
  100. unsigned cd_bit;    A bit mask for the modem input status
  101.             function. This should be used by the
  102.             _dsr() function (below) for testing
  103.             for Carrier Detect. It is set by the
  104.             main() of the program, with some sort
  105.             of default. If desired, the default can
  106.             be changed by the driver at init() time.
  107.  
  108. TIMER PARAMETERS:
  109.  
  110. long millisec;        These are incremented as millisecond
  111. long millis2;        counters. The resolution is 1 millisec;
  112.             however, high accuracy is not required. For
  113.             the IBM PC, 55 is added every timer tick,
  114.             and is close enough. For a 10 mS timer tick,
  115.             add 10, etc.
  116.  
  117. int seconds;        Incremented at the same time as millisec,
  118. int minutes;        above. Seconds should run from 0 to 59, then
  119.             be cleared to zero, and minutes incremented. 
  120.             Minutes increments indefinitely; there is
  121.             no hours counter.
  122.  
  123.  
  124.  
  125. FUNCTIONS:
  126.  
  127. scrinit()        Set all the abovementioned screen variables.
  128.             This is always called before any screen
  129.             access is done.
  130.  
  131. init()            Full hardware initialization. This sets up
  132.             any interrupt structures, calls scrinit(),
  133.             and performs any other initialization
  134.             necessary to make the hardware usable. This
  135.             should also raise the DTR line, if any 
  136.             (described below). There is a matching 
  137.             function, uninit().
  138.  
  139.             This should start the clock ticking, and the
  140.             'minutes' variable incremented once per
  141.             minute. See NOTES, below, on a function to
  142.             perform this.
  143.  
  144. uninit()        Take down any initialization necessary before
  145.             returning to DOS, such as clock interrupts.
  146.             NOTE: This should NEVER disturb the current
  147.             state of DTR. This is to allow one program
  148.             to terminate, and take control of the modem,
  149.             without losing carrier. See NOTES on taking
  150.             down the clock.
  151.  
  152. baud(rate)        Set the baud rate of the serial port or
  153.             modem. 'rate' is the desired baud rate; it
  154.             returns the baud rate set, or zero if that 
  155.             rate is not supported.
  156.  
  157. _mconstat()        Returns 0 if no character ready at the modem,
  158.             else any non-zero value. Do not remove the
  159.             character from the modem. Non-destructive
  160.             reads are performed at the next highest layer.
  161.  
  162. _mconin()        Returns the contents of the modem data port. 
  163.             Wait for a character if necessary. Must return
  164.             an 8 bit value.
  165.  
  166. _mconostat()        Return true if the modem is ready to accept
  167.             a character.
  168.  
  169. _mconout(c)        Output character 'c' to the modem. Wait for
  170.             output ready if necessary.
  171.  
  172. _cd()            Return true if CD is
  173.             true. This reads whatever status port, masks
  174.             it with the cd_bit value, and if true, returns
  175.             true. 
  176.             
  177. lower_dtr()        Drop a modem output control line. The
  178.             actual line used depends on the hardware.
  179.  
  180. raise_dtr()        Raise a modem control line. This also
  181.             depends on the hardware. It should be
  182.             called by init().
  183.  
  184. _mflush()        Flushes both (if any) input and output
  185.             buffers.
  186.  
  187. _mbreak(n)        Set a line break (n != 0) or remove a line
  188.             break. (n == 0). 
  189.  
  190.  
  191. TIMER FUNCTIONS:
  192.  
  193. set_clk();        Start the timer running, and incrementing
  194.             the TIMER PARAMETERS, mentioned above.
  195.  
  196. clr_clk();        Clears all of the timer counters to zero;
  197.             millisec, millis2, seconds, minutes.
  198.  
  199. reset_clk();        Removes the clock timer.
  200.  
  201.  
  202. CRT FUNCTIONS:
  203.  
  204.  
  205. _lconout()        Optional function. The default one is in the
  206.             XENIX library, which goes through the DOS.
  207.             Create this one for custom applications
  208.             or raw speed.
  209.  
  210.             Note that MSDOS redirection cannot be used
  211.             if this function is invoked. If redirection
  212.             is needed, write an _lconout() in the main
  213.             function, that uses MSDOS calls.
  214.  
  215. place(line,col)        Place cursor at the specified line and 
  216.             column. Input has already been bounded and 
  217.             error checked; code for speed. The passed
  218.             line number starts at 0 (top of screen)
  219.             and columns start at 0 (left edge of screen.)
  220.  
  221.             Avoid the use of printf(), etc, or anything 
  222.             else in "higher" level libraries. Use the 
  223.             local _lconout(), as this function wont be 
  224.             used if the program can use redirection.
  225.  
  226. clreol()        Clear from current cursor position to end 
  227.             of line. Do not move the cursor. 
  228.  
  229. insline()        Insert a blank line at the current cursor
  230.             line, and scroll the line under the cursor,
  231.             and all below it, down one. The inserted
  232.             line does not have to have any specific 
  233.             contents. Code for speed.
  234.  
  235. delline()        Delete a line at the current cursor line.
  236.             The line under the cursor disappears, and
  237.             all lines below it scroll up one. The 
  238.             bottom line does not have to be cleared.
  239.